Skip to content

docs: document the $files and $branches system tables - #669

Merged
JingsongLi merged 2 commits into
apache:mainfrom
jackylee-ch:docs/system-tables-files-branches
Aug 6, 2026
Merged

docs: document the $files and $branches system tables#669
JingsongLi merged 2 commits into
apache:mainfrom
jackylee-ch:docs/system-tables-files-branches

Conversation

@jackylee-ch

Copy link
Copy Markdown
Contributor

$files and $branches are registered system tables — SYSTEM_TABLE_NAMES lists
both, and the 0.3.0 release notes already advertise $files — but the SQL
reference documented only 9 of the 11, so users had no way to learn the column
names without reading system_tables/files.rs. $files is the most useful of the
set for debugging compaction and skew, which makes the omission the more visible
one.

Fix: add a ### $files and a ### $branches section to docs/src/sql.md,
following the existing $tags/$table_indexes shape (purpose sentence, sample
query, column table). Column names and order are taken verbatim from
files_schema() (20 columns) and branches_schema() (2 columns); Arrow types are
rendered in the SQL spelling the surrounding sections already use. The
$branches section also notes the one behavior that sets it apart from its
neighbours: it ignores a $branch_<name> prefix and always reports the base
table's branches.

Docs only — no code or test changes.

Comment thread docs/src/sql.md Outdated
Comment thread docs/src/sql.md Outdated
@jackylee-ch

Copy link
Copy Markdown
Contributor Author

@QuakeWang PTAL

@JingsongLi JingsongLi left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

@JingsongLi
JingsongLi merged commit 81b029a into apache:main Aug 6, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants